<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>ransampl: a C library for random number sampling</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@localhost" />
</head>

<body style="background-color: white">


<!-- INDEX BEGIN -->
<div name="index">
<p><a name="__index__"></a></p>
<!--

<ul>

	<li><a href="#name">NAME</a></li>
	<li><a href="#synopsis">SYNOPSIS</a></li>
	<li><a href="#description">DESCRIPTION</a></li>
	<li><a href="#example">EXAMPLE</a></li>
	<li><a href="#copying">COPYING</a></li>
	<li><a href="#see_also">SEE ALSO</a></li>
</ul>

-->


</div>
<!-- INDEX END -->

<link rel="stylesheet" href="podstyle.css" type="text/css" /><p>
</p>
<hr />
<h1><a name="name">NAME</a></h1>
<p>ransampl - random number sampling</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<p><strong>#include &lt;ransampl.h</strong>&gt;</p>
<p><strong>ransampl_ws* ransampl_alloc( int</strong> <em>n</em> <strong>);</strong></p>
<p><strong>void ransampl_set( ransampl_ws *</strong><em>ws</em><strong>, double *</strong><em>p</em> <strong>);</strong></p>
<p><strong>int ransampl_draw( ransampl_ws *</strong><em>ws</em><strong>, double</strong> <em>ran1</em><strong>, double</strong> <em>ran2</em> <strong>);</strong></p>
<p><strong>void ransampl_free( ransampl_ws *</strong><em>ws</em> <strong>);</strong></p>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>These routines allow to draw a random index according to given probabilities <em>p</em>[0], .., <em>p</em>[<em>n</em>-1].</p>
<p>The implementation uses the alias method of Walker and Vose in a form given by Schwarz.  Using precomputed tables, the cost for a single drawing is only O(1).  Therefore this is the recommended method for <em>M</em> drawings if <em>M</em>&gt;&gt;<em>n</em>&gt;&gt;1.</p>
<p>To prepare, a workspace must be allocated by <strong>ransampl_alloc</strong>,
and some tables must be precomputed by <strong>ransampl_set</strong>.  
The supplied probabilities <em>p</em> are not requested to be normalized.</p>
<p>For each random drawing, the user must supply two uniform random numbers <em>ran1</em>, <em>ran2</em> to <strong>ransampl_draw</strong>.</p>
<p>Finally, <strong>ransampl_free</strong> deallocates the workspace.</p>
<p>
</p>
<hr />
<h1><a name="example">EXAMPLE</a></h1>
<p>Draw representative inhabitants according to the given population numbers
of nine federal states of Austria. This example is also contained in the source distribution, demo/sampling1.c.</p>
<pre>
    #include &lt;stdio.h&gt;
    #include &lt;gsl/gsl_rng.h&gt;
    #include &quot;ransampl.h&quot;
    
    int main()
    {
        const int M=1000000;
        int i, m;
    
        // Discrete probability distribution example:
        const int n = 9;
        // states of Austria
        const char* names[] = {
            &quot;Wien&quot;, &quot;Niederoesterreich&quot;, &quot;Oberoesterreich&quot;,
            &quot;Tirol&quot;, &quot;Kaernten&quot;, &quot;Salzburg&quot;,
            &quot;Vorarlberg&quot;, &quot;Burgenland&quot;, &quot;Steiermark&quot; };
        // inhabitants in millions as of 2011 [www.statistik.at]
        double p[] = { 1.721573, 1.614661, 1.415020,
                        .711161,  .558056,  .532713,
                        .370833,  .285377,  .1211506 };
    
        // Initialize random number generator:
        gsl_rng_env_setup();
        gsl_rng* rng = gsl_rng_alloc( gsl_rng_default );
    
        // Allocate workspace, and precompute tables:
        printf( &quot;Precomputing tables ...\n&quot; );
        ransampl_ws* ws = ransampl_alloc( n );
        ransampl_set( ws, p );
    
        // Draw M random samples; accumulate histogram 'cumul':
        printf( &quot;Drawing %i samples ...\n&quot;, M );
        double cumul[n];
        for ( i=0; i&lt;n; ++i )
            cumul[i] = 0;
        for ( m=0; m&lt;M; ++m ) {
            i = ransampl_draw( ws,
                               gsl_rng_uniform(rng),
                               gsl_rng_uniform(rng) );
            cumul[i] += 1;
        }
    
        // Print given probability and obtained frequency:
        printf( &quot;Result (input-&gt;output):\n&quot;);
        double sum = 0;
        for ( int i=0; i&lt;n; ++i )
            sum += p[i];
        printf( &quot;  %-18s  %-9s  %-9s  %-9s\n&quot;,
                &quot;state&quot;, &quot;N (Mio.)&quot;, &quot;rel&quot;, &quot;sim&quot; );
        for ( int i=0; i&lt;n; ++i )
            printf( &quot;  %-18s  %9.7f  %9.7f  %9.7f\n&quot;,
                    names[i], p[i], p[i]/sum, ((double)cumul[i])/M );
    
        // Free workspace and terminate:
        ransampl_free( ws );
        return 0;
    }</pre>
<p>
</p>
<hr />
<h1><a name="copying">COPYING</a></h1>
<p>Copyright (C): Joachim Wuttke 2013, Forschungszentrum Juelich GmbH</p>
<p>Software: FreeBSD License</p>
<p>Documentation: Creative Commons Attribution Share Alike</p>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p>Homepage: <a href="http://apps.jcns.fz-juelich.de/ransampl">http://apps.jcns.fz-juelich.de/ransampl</a></p>
<p>Please report bugs to the author &lt;<a href="mailto:j.wuttke@fz-juelich.de">j.wuttke@fz-juelich.de</a>&gt;</p>

</body>

</html>
